/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */

package cgl.granules.dataset;

import java.io.IOException;
import java.util.Iterator;

/**
 * The <code>DataCollection</code> interface manages a collection of datasets
 * that would be operated upon by an application instance.
 * 
 * @author Shrideep Pallickara
 * 
 */

public interface DatasetCollection {
	/**
	 * Reports on the availability of data in any of the underlying datasets
	 * that are part of this collection.
	 * 
	 * @return <code>true</code> if data is available on any of the underlying
	 *         datasets;<code>false</code> otherwise.
	 */
	public boolean isDataAvailable();

	/**
	 * This method indicates whether this dataset collection is closed. If all
	 * the constituent datasets report on their closure, this method will return
	 * true.
	 * 
	 * @return <code>true</code> if this dataset is closed;<code>false</code>
	 *         otherwise.
	 */
	public boolean isClosed();

	/**
	 * Get the number of datasets in this collection.
	 * 
	 * @return the total number of datasets now in this collection.
	 */
	public int getNumberOfDatasets();

	/**
	 * Add a dataset to this collection.
	 * 
	 * @param dataset
	 *            The dataset to be added to the collection in question.
	 * @return the total number of datasets now in this collection.
	 * @throws DatasetException
	 *             If there are problems adding this dataset to the collection
	 */
	public int addDataset(Dataset dataset) throws DatasetException;

	/**
	 * Remove a dataset from this collection
	 * 
	 * @param datasetIdentifier
	 *            The identifier of the dataset that needs to be removed.
	 * @return the total number of datasets now in this collection.
	 * @throws DatasetException
	 *             If there are problems removing this dataset from the
	 *             collection.
	 */
	public int removeDataset(String datasetIdentifier) throws DatasetException;

	/**
	 * Check to see if any dataset is part of this collection.
	 * 
	 * @return <code>true</code> if there are registered datasets, and
	 *         <code>false</code> otherwise.
	 */
	public boolean hasDataset();

	/**
	 * Check to see if a dataset with the specified identifier is part of this
	 * collection
	 * 
	 * @param datasetIdentifier
	 * @return <code>true</code> if the dataset with specified identifier is
	 *         part of this collection;<code>false</code> otherwise.
	 * @throws DatasetException
	 *             If the specified datasetIdentifier is a NULL
	 */
	public boolean hasDataset(String datasetIdentifier) throws DatasetException;

	/**
	 * Retrieve a specific dataset
	 * 
	 * @param datasetIdentifier
	 *            The identifier of the dataset.
	 * @return The dataset with the specified dataset identifier
	 * @throws DatasetException
	 *             If there are problems retrieving the dataset.
	 */
	public Dataset getDataset(String datasetIdentifier) throws DatasetException;

	/**
	 * Retrieve an iterator to iterate over the datasets.
	 * 
	 * @return The iterator to iterate over the datasets.
	 */
	public Iterator<Dataset> getDatasets();

	/**
	 * Register an observer for the DatasetCollection
	 * 
	 * @param observer
	 *            The observer being registered.
	 */
	public void setDatasetCollectionObserver(DatasetCollectionObserver observer);

	/**
	 * Resume data availability notifications for this collection. Notifications
	 * are automatically paused, when an availability is reported once.
	 */
	public void resumeAvailabilityNotifications();

	/**
	 * Initializes all the constituent datasets in this collection.
	 * 
	 * @throws DatasetException
	 *             If there are problems initializing any of the datasets within
	 *             the dataset collection.
	 */
	public void initializeDatasets() throws DatasetException;

	/**
	 * Returns this collection as a stream of bytes.
	 * 
	 * @return The byte[] representation of the dataset.
	 * @throws IOException
	 *             If there are problems marshalling this dataset.
	 */
	public byte[] getBytes() throws IOException;

}
